." The first line of this file must contain the '"[e][r][t][v] line
." to tell man to run the appropriate filter "t" for table.
." vim: set filetype=nroff :
."
."	$Id$
."
."######################################################################
."#									#
."#			   Copyright (C)  2004				#
."#	     			Internet2				#
."#			   All Rights Reserved				#
."#									#
."######################################################################
."
."	File:		owampd.8
."
."	Author:		Jeff Boote
."			Internet2
."
."	Date:		Fri May  7 15:24:16 MDT 2004
."
."	Description:	
."
.de TQ
.br
.ns
.TP \\$1
..
.TH owampd 8 "$Date$"
.SH NAME
owampd \- One-way latency server.
.SH SYNOPSIS
.B owampd
[\fIoptions\fR]
.SH DESCRIPTION
.B owampd
is a server program specifically designed to run one side of one-way
latency tests. The client program \fBowping\fR is available to run
the other side of the test.
.PP
Aside from actually running the tests, the main function of \fBowampd\fR
is to determine which tests are allowed, based upon the policy restrictions
configured by the system administrator.
.PP
\fBowampd\fR was designed to be run as a stand-alone daemon process. It
uses the classic accept/fork model of handling new requests.
.PP
Most of the command line options for \fBowampd\fR have analogous options
in the \fBowampd.conf\fR file. The command line takes precedence.
.SH OPTIONS
.TP
.BI \-a " authmode"
Specify the authentication modes the server is willing to use for
communication. \fIauthmode\fR should be set as a character string with
any or all of the characters "AEO". The modes are:
.RS
.IP \fBA\fR
[\fBA\fR]uthenticated. This mode encrypts the control connection and
encrypts part of each test packet.
.IP \fBE\fR
[\fBE\fR]ncrypted. This mode encrypts the control connection and
encrypts each test packet in full. (This mode forces an encryption step
between the fetching of a timestamp and when the packet is sent. This
adds more computational delay to the time reported by \fBOWAMP\fR for each
packet.)
.IP \fBO\fR
[\fBO\fR]pen. No encryption of any kind is done.
.PP
The server can specify all the modes with which it is willing to communicate.
The most strict mode that both the server and the client are willing to use
will be selected.
.IP Default:
"AEO".
.RE
.TP
.BI \-c " confdir"
Specify the directory that holds the \fBowampd\fR configuration files:
\fBowampd.conf\fR, \fBowampd.limits\fR and \fBowampd.pfs\fR.
.RS
.IP Default:
Current working directory.
.RE
.TP
.BI \-d " datadir"
Specify the directory that holds the buffered data files. The data files are
the result of one-way latency tests where the server is the receiving
host. The data files are used to buffer the data, at least until a client
downloads the file. Policy restrictions can be used to set how much disk space
a given connection can use, as well as to determine when each file
is deleted. (See the \fBowampd.limits(5)\fR manual page.)
.RS
.IP Default:
Current working directory.
.RE
.TP
.BI \-e " facility"
Syslog \fIfacility\fR to which messages are logged.
.RS
.IP Default:
LOG_DAEMON
.RE
.TP
.B \-f
Disables the requirement that \fBowampd\fR be run
with \fInon-root\fR permissions. There are legitimate reasons to run
.B owampd
as root, but it is more risky. (For example, some operating systems
require root permissions to set the TOS bits used by the \fI\-D\fR
option of \fBowping\fR.) This additional option was
added to ensure that root permissions are only used when explicitly
intended.
.TP
.BI \-G " group"
Specify the gid for the \fBowampd\fR process. \fIgroup\fR can
be specified using a valid group name or by using \-gid. This option is
only used if \fBowampd\fR is started as root.
.RS
.PP
This option can be useful to limit logfile permissions to only users in
this group.
.RE
.TP
.B \-h
Print a help message.
.TP
.BI \-P " 0 | lowport-highport"
Specify the specific port range to use on the local host for
.I OWAMP-Test
packets. This can be specified in two ways. First, as 0 which would indicate
.B owampd
should allow the system to pick the port (ephemeral). Second, as a range:
.I lowport
must be a smaller value than
.I highport
and both numbers must be valid port values. (16 bit unsigned integer values)
.RS
.IP Default:
0
.RE
.TP
.BI \-R " vardir"
Specify the directory to hold the owampd.pid file.
.RS
.IP Default:
Current working directory
.RE
.TP
.BI \-S " nodename:port"
Specify the address and port on which \fBowampd\fR will listen for requests.
\fInodename\fR can be specified using a DNS name or using the textual
representation of the address. It is possible to set the source address,
without setting the \fIport\fR, simply by leaving off the ':' and \fIport\fR
specification. Likewise, a non-default port can be specified for
all system addresses (wildcard) by starting the specification string with
a ':'. If an IPv6 address is specified, note that the accepted format
contains \fInodename\fR in square brackets, such as: [fe80::fe9f:62d8]. This
ensures the port number is distinct from the address specification.
.RS
.IP Default:
\fInodename\fR is wildcarded as any currently available address.
\fIport\fR is 861.
.RE
.TP
.BI \-U " user"
Specify the uid the \fBowampd\fR process should run as. \fIuser\fR
can be specified using a valid user name or by using \-uid.
This option is only used if \fBowampd\fR is started as root.
.RS
.PP
In the default case, \fBowampd\fR should be started as root so it can bind
the protected port 861. (See \-S option.) \fBowampd\fR will release root
permissions shortly after binding to this protected port and requests will
be serviced by processes running with permissions defined by the \fIuser\fR.
.RE
.TP
.B \-v
Set verbose output. Messages will still only go to syslog unless the \fB\-Z\fR
option is specified.
.TP
.B \-Z
Run the master \fBowampd\fR process in the foreground. In this mode, error
messages are printed to STDERR as well as being sent to syslog. Also, normal
terminal controls are available. (i.e., <Cntr\-C> will cause the daemon to
kill it's child processes and exit.) This is useful for debugging.
.SH REQUIREMENTS
The \fBowampd\fR daemon requires a very well synchronized and stable clock.
\fBowampd\fR requires that \fBNTP\fR be running to synchronize
the system clock. \fBNTP\fR needs to be setup in a more methodical way
than on most systems for the results to be meaningful. Please see the
\fBOWAMP\fR web site \%(http://e2epi.internet2.edu/owamp/) for details
concerning proper configuration of \fBNTP\fR for \fBOWAMP\fR.
.SH ERRORS
\fBowampd\fR uses \fBsyslog\fR to output error messages including access
information. The \fIfacility\fR configuration option is used to determine
what \fBsyslog\fR facility is used. The levels used are as follows:
.IP \fBLOG_ERR\fR
Used for messages indicating fatal errors. The requested action will not
be performed.
.IP \fBLOG_WARNING\fR
Used for messages indicating an unexpected or dangerous condition.
.IP \fBLOG_INFO\fR
Used for access messages.
.IP \fBLOG_DEBUG\fR
Used to indicate reasons for actions. For example, if an access is denied
due to policy choices that will be noted with this log level.
.PP
These levels were chosen to give the system-administrator the ability to
separate access log information from error log information in a straight
forward manner.
.SH SIGNALS
.
The \fBowampd\fR process makes use of a number of signals to perform
IPC between the various processes involved:
.TP
\fBSIGALRM\fR
Used throughout to set timers where appropriate.
.TP
\fBSIGCHLD\fR
Used to keep track of the state of child processes.
.TP
.B SIGINT
.TQ
.B SIGTERM
.TQ
.B SIGHUP
Used to terminate any \fBowampd\fR process. These signals are caught by the
parent daemon and it manages the complete shutdown of all the \fBowampd\fR
processes.
.TP
\fBSIGPIPE\fR
Disabled throughout \fBowampd\fR.
.TP
\fBSIGUSR1\fR
Used to tell a spawned off receiver/sender process that all control
setup interaction is complete and the test can continue at the
determined time. (This is an indication that the StartSessions message
was received for those familiar with the \fBOWAMP\fR protocol.)
.TP
\fBSIGUSR2\fR
Used to tell a spawned off receiver/sender process to terminate a session
early. (This is an indication that a StopSessions message was received
for those familiar with the \fBOWAMP\fR protocol.)
.SH FILES
owampd.pid
.br
owampd.conf
.br
owampd.limits
.br
owampd.pfs
.SH ENVIRONMENT VARIABLES
\fBOWAMP\fR uses environment variables for some debugging options.
.TS
lb lb
_ _
lb li .
OWAMP Environment Variable	Description

OWAMP_DEBUG_TIMEOFFSET	Offset time by this amount (seconds)
.TE
.SH SEE ALSO
There are more details on configuring the \fBowampd\fR daemon in the
owampd.conf(5) manual page. Details on configuring the policy
are in the owampd.limits(5) and owampd.pfs(5) manual pages.
Information on the client is in the owping(1) manual page.
For more of an overview of the full functionality and architecture, see
the \%http://e2epi.internet2.edu/owamp/ web site.
.SH ACKNOWLEDGMENTS
This material is based in part on work supported by the National Science
Foundation (NSF) under Grant No. ANI-0314723. Any opinions, findings and
conclusions or recommendations expressed in this material are those of
the author(s) and do not necessarily reflect the views of the NSF.
